业务内置API

提供具体业务对象的内置前端能力，供客开代码能够使用到标准产品的能力快速、高效的实现部分复杂业务逻辑，并且能够保持与标准功能的逻辑互洽。目前提供的能力都是通过Execute Command的方式进行调用。

公共

1. 设置日期字段的最大日期 Commands:`Commands.Common_SetMaxDate`

调用入参说明

参数	类型	说明
path	String	字段名称, 子表则为: stages.planStartDate
value	Date	日期值

使用示例

thisApp.formOnLoad = async (ctx) => {
    // 设置日期字段的最大日期
    ctx.executeCommand(Commands.Common_SetMaxDate, {
        path: "planStartDate",
        value: new Date(),
    });
};

2. 设置日期字段的最小日期 Commands:`Commands.Common_SetMinDate`

调用入参说明

参数	类型	说明
path	String	字段名称, 子表则为: stages.planStartDate
value	Date	日期值

使用示例

thisApp.formOnLoad = async (ctx) => {
    // 设置日期字段的最小日期
    ctx.executeCommand(Commands.Common_SetMinDate, {
        path: "planStartDate",
        value: new Date(),
    });
};

3. 设置日期组件的minuteStep Commands: `Commands.Common_SetMinuteStep`

调用入参说明

参数	类型	说明
path	String	字段名称, 子表则为: stages.planStartDate
value	Number	分钟间隔

使用示例

thisApp.formOnLoad = async (ctx) => {
    // 设置日期组件的minuteStep
    ctx.executeCommand(Commands.Common_SetMinuteStep, {
        path: "csRiQi",
        value: 30,
    });
};

4. 根据来源单据生成当前单据数据 Commands:`Commands.Common_SelectSourceData`

调用入参说明
参数类型说明
objectType String 来源单据
billTypeId String 来源单据类型id
businessTypeId String 来源业务类型id
ids String 来源的单据id集合
使用示例

参数	类型	说明
objectType	String	来源单据
billTypeId	String	来源单据类型id
businessTypeId	String	来源业务类型id
ids	String	来源的单据id集合

thisApp.formOnLoad = async (ctx) => {
    ctx.executeCommand(Commands.Common_SelectSourceData, {
        objectType: "ArContract",
        billTypeId: "xxxx1",
        businessTypeId: "xxxx1",
        ids: ["xxxx1"]
    })
};

基础档案

客户、供应商申请单档案查重

适用范围： 仅支持 Web 端客户申请单、供应商申请单表单；不支持移动端，也不影响列表页查重。

1. 注册自定义查重回调 Commands:`Commands.RegisterCheckArchiveDuplicate`

概要业务逻辑
注册后，客户或供应商名称字段后缀、表头查重按钮的点击将由自定义回调接管；未注册时保持系统默认查重行为。后一次注册会覆盖前一次注册，表单销毁时自动释放回调。
自定义回调不会自动执行系统默认查重；若需要执行当前入口原有的查重流程，请显式调用 api.click()。自定义回调抛出异常时，系统也不会自动回退执行默认查重。
调用入参说明

参数	类型	说明
callback	`({ api, mode }) => void \\| Promise<void>`	自定义查重回调
mode	`"Create" \\| "Edit" \\| "View"`	当前表单模式，分别表示新增、编辑和查看
api	`CheckArchiveDuplicateApi`	档案查重操作 API

CheckArchiveDuplicateApi 说明

方法	返回值	说明
`getFormValue()`	`Record<string, any>`	返回当前表单的完整普通 JSON 数据
`writeBackToForm(data, newTab, isReuseRow?)`	`void`	将查重结果回写到当前表单或同实体的新建页签；`isReuseRow` 默认为 `true`
`click()`	`void \\| Promise<void>`	执行触发当前自定义回调的入口原有查重流程，不会再次进入自定义回调

writeBackToForm 入参说明

参数	类型	说明
data	`Record<string, any>`	待回写的主表和子表数据
newTab	`boolean`	是否打开同实体新建页签进行回写
isReuseRow	`boolean`	可选，追加子表时是否复用末尾连续空行，默认为 `true`

回写规则
- Create 或 Edit 模式且 newTab=false 时，直接回写当前表单。
- View 模式下会强制按 newTab=true 处理。
- newTab=true 时，打开当前实体的新建表单，继承当前单据类型和组织。每次打开都携带唯一路由参数，不会替换已打开的同实体表单页签。newTab=false 则会直接更改当前表单数据
- 主表字段按字段名赋值；引用字段可传递完整引用对象。
- 子表数据格式为 { 子表字段名: [行对象, ...] }，通过追加行的方式回写，不会覆盖已有非空行。
- isReuseRow=true 时优先复用子表末尾连续空行；传入 false 时始终追加新行。
- 空子表数组不处理；子表值必须是数组。
- 自动忽略 id、值为 undefined 的字段及目标实体中不存在的字段。
使用示例

thisApp.formOnLoad = async (ctx) => {
    ctx.executeCommand(
        Commands.RegisterCheckArchiveDuplicate,
        async ({ api, mode }) => {
            const currentValue = api.getFormValue();

            // 在此执行自定义查重，例如打开虚拟表单让用户确认回写数据。
            const writeBackData = {
                name: `${currentValue.name || "测试客户"}-查重回写`,
                abbrName: "测试客户",
                telephone: "13800138000",
                addresses: [
                    {
                        country: { id: "xxxx1", name: "中国" },
                        address: "北京市朝阳区测试路1号",
                        isDefault: true,
                    },
                    {
                        country: { id: "xxxx1", name: "中国" },
                        address: "上海市浦东新区测试路2号",
                        isDefault: false,
                    },
                ],
            };

            // 查看态即使传入 false，也会打开新建页签。
            // 第三个参数为是否复用子表空行，省略时默认为 true。
            api.writeBackToForm(writeBackData, mode === "View", true);

            // 如需执行当前入口原有查重，可显式调用：
            // await api.click();
        }
    );
};

升级提示： 自定义回调的注册命令已由 Commands.CheckArchiveDuplicate 更名为 Commands.RegisterCheckArchiveDuplicate。旧脚本如果仍在 formOnLoad 中使用 Commands.CheckArchiveDuplicate 注册回调，进入页面时会立即执行默认查重并弹出查重窗口。

2. 执行默认查重 Commands:`Commands.CheckArchiveDuplicate`

概要业务逻辑
直接执行客户或供应商申请单的系统默认表头查重流程。即使已经通过 Commands.RegisterCheckArchiveDuplicate 注册了自定义回调，该命令也不会进入自定义回调。
调用入参说明

参数	类型	说明
无		无

使用示例

thisApp.formOnLoad = async (ctx) => {
    ctx.getPageContext().getActionBar().addButton({
        key: "defaultArchiveDuplicateCheck",
        text: "默认查重",
        onClick: async () => {
            await ctx.executeCommand(Commands.CheckArchiveDuplicate);
        },
    });
};

附件

1. 控制附件的上传，编辑，删除按钮是否显示 Commands:`Commands.Attachment_SetActionDisabled`

调用入参说明

参数	类型	说明
action	String	操作类型，可选值为：`upload`、`edit`、`delete`
disabled	Boolean	是否禁用操作，true为禁用，false为启用

使用示例

thisApp.formOnLoad = async (ctx) => {
    // 禁用附件的上传功能
    ctx.executeCommand(Commands.Attachment_SetActionDisabled, {
        action: "upload",
        value: false
    })
};

项目管理

项目计划

1. 新增 "子级任务" Commands: `Commands.ProjectSchedule_AddSubTask`

概要业务逻辑
根据当前行的任务判断是否能新增下级任务（里程碑任务和已完成的末级任务无法新增下级），若不符合校验逻辑将直接通过弹窗提示错误信息；通过前置性校验后将根据当前任务编号和属性增加下级任务，同时清空与父级任务的约束关系。
业务适用范围：项目任务明细表。
调用入参说明

参数	类型	说明
rowIndex	Number	基准任务所在的行序号，将对当前基准任务新增下级任务

返回值
Boolean: 代表新增子任务的成功状态。
使用示例

thisApp.fieldOnChanged = async (ctx) => {
    const form = ctx.getFormContext().form;
    const currentCtx = ctx.getCurrentContext();
    const { subGridName, subGridLine, currentField,fieldName } = currentCtx
    // 任务子表的部门值发生变化，且部门编码是1001时执行新增 “子集任务”
    if (fieldName === "department" && subGridName === "tasks") {
        const value = currentField.value
        if (value.code === "1001") {
            const result = ctx.executeCommand(Commands.ProjectSchedule_AddSubTask, { rowIndex: subGridLine })
            if (result === true) {
               return qiqi.ui.message.showSuccess("新增下级成功")
            }
            return qiqi.ui.message.showError("新增下级任务失败")
        }
    }
};

2. 生成制约关系 Commands: `Commands.ProjectSchedule_CreateDependent`

概要业务逻辑
在编辑状态下，将所有未开始的任务的前置任务进行清除；并重新生成任务的制约关系。
调用入参说明

参数	类型	说明
isSilent	Boolean	是否静默执行（静默模式下不进行用户交互弹窗）

返回值
Promise<void> 无返回值
使用示例

thisApp.fieldOnChanged = async (ctx) => {
    const form = ctx.getFormContext().form;
    const currentCtx = ctx.getCurrentContext();
    if (currentCtx.currentField.name === "businessDate") {
        onBusinessDateChanged(ctx)
        return 
    }
};

/**
 * 业务日期变化后，创建制约关系或者取消关系；
 * 随机静默处理。
 */
function onBusinessDateChanged(ctx) {
    const value = ctx.getCurrentContext().currentField.value
    if (typeof value !== "object" || !(value instanceof Date)) {
        return
    }
    // 随机进行控制是否静默处理。
    const isSilent = parseInt(Math.random() * 10) % 2 === 0;

    // 如果日期是在周末，则取消制约关系；否则生成制约关系。
    const workDay = value.getDay()
    if (!workDay || workDay === 6) {
        Commands
        ctx.executeCommand("ProjectSchedule_ClearAllDependent", { isSilent})
    } else {
        ctx.executeCommand("ProjectSchedule_CreateDependent", { isSilent})
    }
    return 
}

3. 取消制约关系 Commands: `Commands.ProjectSchedule_ClearAllDependent`

概要业务逻辑
在编辑状态下，将所有未开始的任务的前置任务进行清除；并取消任务的制约关系。
调用入参说明

参数	类型	说明
isSilent	Boolean	是否静默执行（静默模式下不进行用户交互弹窗）

返回值
Promise<void> 无返回值
使用示例
参考 生成编制关系 的使用案例。

4. 自动编排 Commands: `Commands.ProjectSchedule_AutoSchedule`

概要业务逻辑
在编辑状态下，开启自动编排后，任务会自动根据制约关系进行处理开始时间。此命令是toggle模式，即关闭模式下调用是打开，打开模式下调用是关闭。
调用入参说明

参数	类型	说明
isSilent	Boolean	是否静默执行（静默模式下不进行用户交互弹窗）

返回值
Promise<boolean>: 命令调用过后的自动编排的设置状态。
使用示例

thisApp.formOnInit = async (ctx) => {
    ctx.getPageContext().getActionBar().addButton({
        key: 'autoSchedule',
        text: '自动编排',
        onClick: async () => {
            const result = await ctx.executeCommand("ProjectSchedule_AutoSchedule")
            qiqi.ui.message.show("自动编排的启用状态：" + result)
        },
    })
};

销售管理、采购管理

取价控制

注：支持自定义按钮的单据可用

1. 运行控制某行是否参与取价 Commands: `Commands.FetchPrice_CanRowFetchPrice`

概要业务逻辑
某些情况下，不需要触发系统默认的取价，可以通过函数过滤某些不需要取价的行
调用入参说明

参数	类型	说明
Fn	(rowData:any) => Boolean	定义过滤函数，判断本条数据是否参与取价，返回 true 或者 false。注：由于内部设计的问题，如果是整单取价（批量取价），这里的行数据是扁平化的，比如存货字段的值就是 rowData.productId,而不是rowData.product.id,所以还请使用两种方式判断

使用示例

thisApp.formOnLoad = async (ctx) => {
    ctx.executeCommand('FetchPrice_CanRowFetchPrice', (rowData) => {
        // 这里还是可以拿到上下文（比如表单）的值进行判断
        const form = ctx.getFormContext().form

        const billTypeId = form.value.billType.id
        if (billTypeId == 'billType1') {
            // 这种单据类型的不触发取价
            return false
        }
        // 对象类型的数据需要判断两种模式
        if (rowData.productId == 'productId1' || (rowData.product && rowData.product.id == 'productId1')) {
            // 这种存货不需要触发取价
            return false
        }
        // 触发取价
        return true
    })
};

2. 控制切换取价因素时是否弹框、是否取价 Commands: `Commands.FetchPrice_Interpret`

概要业务逻辑
支持 FetchPrice_CanRowFetchPrice 的单据均支持此命令。切换供应商、客户、币种等取价因素时，可以通过回调函数控制是否显示重新取价确认框，以及是否继续执行取价。
调用入参说明

参数	类型	说明
Fn	() => { confirm: boolean, fetchPrice: boolean }	定义取价干预函数。`confirm` 控制是否显示重新取价确认框；`fetchPrice` 控制是否继续取价。

回调返回值说明

confirm	fetchPrice	处理结果
true	true	保持系统默认行为：需要确认时弹框，确认后取价；无需确认时直接取价。
false	true	不弹确认框，继续后续流程，符合原取价条件时直接取价。
true / false	false	不弹确认框，也不取价。`fetchPrice: false` 的优先级高于 `confirm`。

使用示例

thisApp.formOnLoad = async (ctx) => {
    ctx.executeCommand('FetchPrice_Interpret', () => {
        return {
            confirm: false,
            fetchPrice: false,
        }
    })
};

采购订单

批量取价

1. 批量取价 Commands: `Commands.FetchPrice_BatchFetchPrice`

概要业务逻辑
执行明细批量取价功能
调用入参说明

参数	类型	说明
showMessage	boolean	批量取价，showMessage为布尔型参数，控制是否展示错误、提示信息

使用示例

// 保存前触发取价
thisApp.onBeforeSave = async (ctx) => {
    const form = ctx.getFormContext().form;
    await ctx.executeCommand('FetchPrice_BatchFetchPrice', true)
};

2. 获取可用量 Commands: `Commands.FetchAvailQty`

概要业务逻辑
执行明细获取可用量功能
调用入参说明

参数	类型	说明
无

使用示例

// 保存前触发获取可用量
thisApp.onBeforeSave = async (ctx) => {
    const form = ctx.getFormContext().form;
    await ctx.executeCommand('FetchAvailQty')
};

3. 获取历史价 Commands: `Commands.FetchHistoryPrice`

概要业务逻辑
执行明细获取历史价功能
调用入参说明

参数	类型	说明
无

使用示例

// 保存前触发获取可用量
thisApp.onBeforeSave = async (ctx) => {
    const form = ctx.getFormContext().form;
    await ctx.executeCommand('FetchHistoryPrice')
};

公共​

1. 设置日期字段的最大日期 Commands:Commands.Common_SetMaxDate​

2. 设置日期字段的最小日期 Commands:Commands.Common_SetMinDate​

3. 设置日期组件的minuteStep Commands: Commands.Common_SetMinuteStep​

4. 根据来源单据生成当前单据数据 Commands:Commands.Common_SelectSourceData​

基础档案​

客户、供应商申请单档案查重​

1. 注册自定义查重回调 Commands:Commands.RegisterCheckArchiveDuplicate​

2. 执行默认查重 Commands:Commands.CheckArchiveDuplicate​

附件​

1. 控制附件的上传，编辑，删除按钮是否显示 Commands:Commands.Attachment_SetActionDisabled​

项目管理​

项目计划​

1. 新增 "子级任务" Commands: Commands.ProjectSchedule_AddSubTask​

2. 生成制约关系 Commands: Commands.ProjectSchedule_CreateDependent​

3. 取消制约关系 Commands: Commands.ProjectSchedule_ClearAllDependent​

4. 自动编排 Commands: Commands.ProjectSchedule_AutoSchedule​

销售管理、采购管理​

取价控制​

1. 运行控制某行是否参与取价 Commands: Commands.FetchPrice_CanRowFetchPrice​

2. 控制切换取价因素时是否弹框、是否取价 Commands: Commands.FetchPrice_Interpret​

采购订单​

批量取价​

1. 批量取价 Commands: Commands.FetchPrice_BatchFetchPrice​

2. 获取可用量 Commands: Commands.FetchAvailQty​

3. 获取历史价 Commands: Commands.FetchHistoryPrice​

公共

1. 设置日期字段的最大日期 Commands:`Commands.Common_SetMaxDate`

2. 设置日期字段的最小日期 Commands:`Commands.Common_SetMinDate`

3. 设置日期组件的minuteStep Commands: `Commands.Common_SetMinuteStep`

4. 根据来源单据生成当前单据数据 Commands:`Commands.Common_SelectSourceData`

基础档案

客户、供应商申请单档案查重

1. 注册自定义查重回调 Commands:`Commands.RegisterCheckArchiveDuplicate`

2. 执行默认查重 Commands:`Commands.CheckArchiveDuplicate`

附件

1. 控制附件的上传，编辑，删除按钮是否显示 Commands:`Commands.Attachment_SetActionDisabled`

项目管理

项目计划

1. 新增 "子级任务" Commands: `Commands.ProjectSchedule_AddSubTask`

2. 生成制约关系 Commands: `Commands.ProjectSchedule_CreateDependent`

3. 取消制约关系 Commands: `Commands.ProjectSchedule_ClearAllDependent`

4. 自动编排 Commands: `Commands.ProjectSchedule_AutoSchedule`

销售管理、采购管理

取价控制

1. 运行控制某行是否参与取价 Commands: `Commands.FetchPrice_CanRowFetchPrice`

2. 控制切换取价因素时是否弹框、是否取价 Commands: `Commands.FetchPrice_Interpret`

采购订单

批量取价

1. 批量取价 Commands: `Commands.FetchPrice_BatchFetchPrice`

2. 获取可用量 Commands: `Commands.FetchAvailQty`

3. 获取历史价 Commands: `Commands.FetchHistoryPrice`